<?php
// $Id$
/**
 * This file contains {@link Query} which is part of the PHP Content Repository 
 * (phpCR), a derivative of the Java Content Repository JSR-170, and is 
 * licensed under the Apache License, Version 2.0.
 *
 * This file is based on the code created for
 * {@link http://www.jcp.org/en/jsr/detail?id=170 JSR-170}
 *
 * @author Travis Swicegood <travis@domain51.net>
 * @copyright PHP Code Copyright &copy; 2004-2005, Domain51, United States
 * @copyright Original Java and Documentation 
 *  Copyright &copy; 2002-2004, Day Management AG, Switerland
 * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, 
 *      Version 2.0
 * @package phpContentRepository
 */

/**
 * Load the {@link phpCR} library file(s)
 */ 
require_once(dirname(__FILE__) . '/../phpCR.library.php');


/**
 * A {@link Query} object.
 *
 * @author PHP - Travis Swicegood <travis@domain51.net>
 * @copyright Copyright &copy; 2004-2005, Domain51
 * @package phpContentRepository
 */
interface Query 
{
   /**
    * Executes this search and returns a {@link QueryResultIterator}.
    *
    * @return object
    */
    public function execute();
    
    
   /**
    * Returns the statement set for this query. Returns NULL
    * if no statement is currently set.
    *
    * @return string
    */
    public function getStatement();
    
    
   /**
    * Returns the language set for this query. 
    *
    * This will be one of the {@link QueryLanguage} constants returned by 
    * {@link QueryManager::getSupportedQueryLanguages()}. 
    *
    * If the query was created using a mechanism outside the specification, 
    * this method may return 0.
    *
    * @see QueryLanguage
    * @return int
    */
    public function getLanguage();
    
    
   /**
    * If this is a persistent query (i.e., it has been saved), returns the path
    * of the {@link Node} that persists it or NULL if it has not
    * been saved.
    *
    * @return string
    */
    public function getPersistentQueryPath();
    
    
   /**
    * Creates a persistent query. 
    *
    * The persisted query will be created as a {@link Node} of {@link NodeType}
    * nt:query. This method persists the new {@link Node}
    * immediately; there is no need to call {@link Node::save()}.
    *
    * @param string
    *   The absolute path at which to persist/save this {@link Query}.
    *
    * @throws {@link ItemExistsException} 
    *   If an {@link Item} already exists at the indicated position
    * @throws {@link PathNotFoundException}
    *   If the path cannot be found
    * @throws {@link ConstraintViolationException}
    *   If creating the {@link Node} would violate a {@link NodeType} (or other 
    *   implementation specific) constraint.
    * @throws {@link RepositoryException} If another error occurs.
    */
    public function save($absPath);
}

